autoNumeric() is a jQuery plugin that formats input fields with numeric strings, supporting most International numeric formats and currency symbols. It automatically places the thousand separator and currency symbol as you type. We have provided two public functions to format and or remove a formats.

Support for International currency formats has never been this easy, flexible and powerful.

Download: autoNumeric-1.7.4-B.js - 'heavy on comments' Donations are appreciated
       

Authors:

I would like to take this opportunity to personally thank Sokolov Yura. Without his expertise and unselfish commitment this update would not have been possible. If anyone is looking for a talented coder I would gladly recommend him - Bob

Key features:

Implementing:

First - include the jQuery.js, autoNumeric-1.7.0.js javascript files in the header. If you are going to use the options also add the metadata plugin.

  <SCRIPT src="jquery-1.5.min.js" type=text/javascript></SCRIPT>

  <SCRIPT src="jquery.metadata.js" type=text/javascript></SCRIPT> <!--when changing defaults-->

  <SCRIPT src="autoNumeric-1.7.4.js" type=text/javascript></SCRIPT>

Second - in a separate script call $('selector').autoNumeric({options}).

$('selector').autoNumeric({options});

Selector - is any valid jQuery selector

options - can be passed here but are not required

 

  // example uses the selector "input" with the class "auto" & no options passed
  jQuery(function($) {
    $('input.auto').autoNumeric();
  });

  // example uses the selector "input" with the class "auto" & with options passed
  // See details below on allowed options
  jQuery(function($) {
    $('input.auto').autoNumeric({aSep: '.', aDec: ','});
  }); 

  // input tag for the above
  <input id="some ID" value="" type="text" class="auto" size="25" />

The example below demonstrates the defaults in the first column. The second and third columns show the Get 'strip' and Set 'format' functions respectively - more on this later.

$('selector').autoNumeric({options}) $('selector').autoNumericGet() $('selector').autoNumericSet(value)
     

Behavior notes: when entering numbers to the left of the decimal separator, the characters entered fills to the left of the insertion point. When the maximum/minimum values are reached additional characters can not be entered. When typing to the right of the decimal separator the caharters also fill to the left with the following exception: if the maximum number of decimal places has been reached and there are numeric characters to the right of the caret postion, any number entered will over write the value to the right so long as the maximum value has not been exceeded.

Defaults and options: There are 11 options that can be used in the metadata code if the defaults do not meet your requirements. I will go through each option (key) and the values that can be changed to obtain the desired format.

Below is an easy to use metadata code generator that should handle most numeric / currency formats. Checking on the options below will generate the metadata code string for the desired format. This can be copied and pasted into your targeted input field.

Note: these are case sensitive and deviating from the suggested options may produce unexpected results.

aSep - controls the thousand separator (note - the thousand & decimal separators can not be the same)

  aSep: ',' - comma (default)
  aSep: '\'' - apostrophe (note: the apostrophe is escaped)
  aSep: '.' - period
  aSep: ' ' - space
  aSep: '' - none

dGroup - controls the digital grouping - the placement of the thousand separator

  dGroup: '3' - produces 333,333,333 (default)
  dGroup: '2' - produces 22,22,22,333 (India's lakhs format)
  dGroup: '4' - produces 4,4444,4444 used in some Asian country's

aDec - controls the decimal (note - the thousand & decimal separators can not be the same)

  aDec: '.' - period (default)
  aDec: ',' - comma

altDec - This was developed to accommodate different keyboard layouts. altDec allows you to declare an alternative key to enter the decimal separator assigned in aDec. Word of caution - use with discretion because it has the potential of being very confusing to your users.

Please note that the full stop on the numeric pad will enter the decimal separator even when the comma is assigned as the decimal separator (aDec: ',').

  altDec: null   - (default)
  - limited to one non-numeric character

aSign - desired currency symbol (examples: € or EUR). Note: other symbols can be used, such as %, °C, °F, km/h & MPH the possibilties are endless.

Note: the currency symbol can not contain an apostrophe, comma or numeric character. NEW - currency symbols with a full stop "period" are now supported. Example "Rs."

Note: Arabic characters are problematic because of the right to left entry - help on modifying the plugin to handle these characters would be appreciated.

Note: There are several currency symbols that are not supported by common fonts (Arial & Tahoma) - I have put together a table you may find useful (Click here to view) of the symbols that are supported by the aforementioned fonts.

Note: Quote marks are automatically added. Spacing between the currency symbol and numeric characters are set using the aSign option. Example no spacing '$' and with spacing '$ ' or ' $' depending on the location (prefix or suffix) of the symbol.

aSign: '' - none (default)
- select option then enter the desired symbol. Click here to view common symbols

pSign - controls the placement of the currency symbol.

  pSign: 'p' - prefix to the left (default)
  pSign: 's' - suffix to the right

Notes on the minimum (vMin) / maximum (vMax) values:

  • The maximum value should always be greater than the minimum value - sorry I had to list this rule!
  • If the minimum / maximum values are both positive or negative you MUST have a default value assigned to the field that is greater than or equal to the minimum value and less than or equal to the maximum value.
  • The number of decimal places is determined from the minimum / maximum values - whichever has value has the greater number of decimal places.
  • The values can contain only numeric characters and one decimal (full stop) character. This metadata code generator automatically places quote marks on the value. If you manually write the metadata code these quote marks are required.
  • The limits of the code generator are 20 significant digits and 10 decimal places - if your requirements exceed these limits you will need to manually adjust the metadata values.

vMin - Enter the minimum value allowed. Allowed values can be whole numbers, floating point, positive, zero or negative.

vMin: '0.00' (default)  
select the option then enter the desired value to the left.

vMax - Enter the maximum value allowed. Allowed values can be whole numbers, floating point, positive, zero or negative.

vMax: '999999999.99' (default)
select the option then enter the desired value to the left.

mDec - Only needed if you want to override the number of decimal places that are determined from the vMin & vMax values.

mDec: null decimal places set via vMin & vMax values (default method)
enter the number of decimal places - this will over ides values set by vMin & vMax

mRound - controls the rounding method. To test the various rounding methods please see below. For in depth details on rounding methods visit the DIY Calculator site.

  mRound: 'S' - Round-Half-Up Symmetric (default)
  mRound: 'A' - Round-Half-Up Asymmetric
  mRound: 's' - Round-Half-Down Symmetric (lower case s)
  mRound: 'a' - Round-Half-Down Asymmetric (lower case a)
  mRound: 'B' - Round-Half-Even "Bankers Rounding"
  mRound: 'U' - Round Up "Round-Away-From-Zero"
  mRound: 'D' - Round Down "Round-Toward-Zero" - same as truncate
  mRound: 'C' - Round to Ceiling "Toward Positive Infinity"
  mRound: 'F' - Round to Floor "Toward Negative Infinity"

aPad - controls padding of the decimal places.

  aPad: true - always pads the decimal with zeros (default)
  aPad: false - no padding - rounding occurs when the decimal length exceeds the decimal places

wEmpty - controls input display behavior.

wEmpty: 'empty' - allows input to be empty (no value) (default)
wEmpty: 'zero' - input field will have at least a zero value
wEmpty: 'sign' - the currency symbol is always present

Metadata code if needed will appear in Red - copy and paste in the input field tag as described above.

 


Various samples: The table below demonstrates the flexibility of the autoNumeric plugin and it's ability to format to different international standards using the above defaults and options.

The 1st column allows the user to enter the values. Multiple formats are demonstrated.

The 2nd column shows the non-formatted numeric values from the 1st column via the Get function.

The 3rd column shows the value from the second column formatted to another standard via the set function.

$('selector').autoNumeric({options}) $('selector').autoNumericGet() $('selector').autoNumericSet(value)


























no metadata

   

Public Functions: the need to format and remove formats for mathematical operations is a must. So two public functions were created that can be called from another script that easily handle these duties. For users of version 1.6.2 and eariler these are much easier to use then in previous versions. Please note: $.autoNumeric.Strip(id, {options} ); & $.autoNumeric.Format(id, value, {options}); still function but it is easy to see that the new versions are superior and they conform to jQuery's convention. The use of setting options via the "autoNumericGet()" & "autoNumericSet()" functions has been depreciated as of version 1.7.2.

$(selector).autoNumericGet(); - This functions strips the formatted string and converts it to a string\value that can be used in mathematical operations - demonstrated in the second column of the above table. Please note:

$(selector).autoNumericSet(value); - This function will format a string\value to the format assigned to the target field. Please note: the argument can be a numeric value or text (9999.99 or '9999.99') - demonstrated in the third column of the above table.

Default values

Guides to follow for default values:

There is one undocumented default "aForm: false". When set to true the default value in the following format "#######.##" will be automatically formatted to the format you have assigned to this field. Please note this feature is a little buggy on page refresh so use at your own risk until a fix is found.

Dynamically loaded values

Assigning values once the page is ready can easily be accomplished with the autoNumericSet() function. Just be sure the string/value does not have any format (99999.99). Here is an example using JSON data on the ready event.

  jQuery(function($) {
    $.getJSON("test_JSON.php", function(data) {
      var valueFormatted = '';
      $.each(data, function(key, value) { // loops through JSON keys and returns value	  
         $('#' + key).autoNumericSet(value);
      });
    });
  // JSON values can be sent as text or numeric values (Note: this has mixed values)
  {
    "idA": "1355.527",
    "idB": "9712547",
    "idC": 0.524, 
    "idD": 135544.5244
  }

Below: a live example of populating the input fields with JSON data on page ready with the above script.









Note: re-load page to retrieve JSON values

Callback function - This may be the most powerful new feature added in this version allowing the return value to be taken as parameter to the default/option key.

Note: Changing the decimal & thousand separator via the callback method can create unexpected results - please use with caution.

There are three methods to use this feature:

1) Pass a "function" when calling autoNumeric via options.

  <script type="text/javascript">		
    var functionName = function(){
      val = 11 * Math.random(); /* example only */ 
    return val; /* return sets the vMax value */
  }

    /* Calls autoNumeric() for the input with the id="someID" and passes a function
    ** note the the function name does NOT use "parenthesis" */																					
    $('#someID').autoNumeric({vMax: functionName}) 
																				
  </script>
																					
  /* The above calls autoNumeric for this input and sets parameter (value) for "vMax:"
  ** no metadata used in the input tag */ 
  <input id="someID" value="" >

2) Pass a "function name" via options\metadata. Note that the function has been attached to autoNumeric previously. The return is taken as a parameter value.

  <script type="text/javascript">

   /* Note function name attached to autoNumeric */
   $.autoNumeric.functionName = function($this, opts, name) { 
     val = 11 * Math.random(); 	/* example only */ 
     return val; 	/* return sets the vMax value */
   }				
														
   /* Calls autoNumeric for the input with the id="someID" */														
   $('#someID').autoNumeric() 
																
  </script>		
																
   /* You can also pass function name via metadata as shown below
  ** the function name is proceeded by "fun:" all is enclosed with "parenthesis" 
  ** the return value from the function is taken as a parameter of "vMax" */										
  <input id="someID" value="" meta="{vMax:'fun:FunctionName'}">

alternative method:

  <script type="text/javascript">

  /* Note function name attached to autoNumeric */
  $.autoNumeric.functionName = function($this, opts, name) { 
    val = 11 * Math.random();  /*example only */ 
    return val;  /* return sets the vMax value */
  }
	
  /* The following method passes the function name via options. 
  ** Note the function name is proceeded by "fun:" all is enclosed with "parenthesis"
  ** In this example the parameter (value) of "vMax" is set */
  $('#someID').autoNumeric({vMax: 'fun:FunctionName'}) 
	
  </script>		

  /* the above calls autoNumeric for this ID and passes the function name to autoNumeric()  
  ** the return value from the function is taken as a parameter of "vMax" */
  <input id="someID" value="">

3) Pass a "css selector" recognized by jQuery via options\metadata - value of input is taken as a parameter value.

  <script type="text/javascript">
							
    /* Calls autoNumeric for the input with the id="someID" */
    $('#someID').autoNumeric() 
						
  </script>		

  /* You can also pass the css selector via metadata as shown below
  ** Note the selector is proceeded by "css:" all is enclosed with "parenthesis" 
  ** This example uses the ID selector that requires the pound sign #
  ** In this example the value of the Selector element sets "aSign" parameter */
  <input id="someID" value="" meta="{aSign:'css:#Selector'}">

  /* The value of the element used as the parameter of "aSign:" */ 
  <select id="selector" >
    <option value="km">Kilometers</option>
    <option value="m">Meters</option>
  </select>

alternative method:

  <script type="text/javascript">
	
    /* The following method passes the CSS selector via options. 
    ** Note the selector is proceeded by "css:" all is enclosed with "parenthesis"
    ** This example uses the ID selector that requires the pound sign #
    ** In this example the value of the Selector element sets "aSign" parameter  */
    $('#someID').autoNumeric({aSign: 'css:#Selector'}) 
							
  </script>		

  /* The above calls autoNumeric for this ID 
  ** no metadata used in the input tag */
  <input id="someID" value="" >

  /* The value of the element used as the parameter of "aSign:" */ 
  <select id="selector" >
    <option value="km">Kilometers</option>
    <option value="m">Meters</option>
  </select>

The following callback demo uses all three callback methods shown above. This simple example allows the user to enter a length in either kilometers (n) or the equivalent amount of meters (n x 1000) and be able to switch back and forth. You will need to change the vMax (maximum) value, the mDEc (decimal places) and the aSign (length abbreviation) depending on which UOM is selected.

Select the preferred unit of measure, then enter the length. You can change the UOM back and forth, each switch changes the values for vMax, aSign & mDec options.

HTML and script for the callback demo:

 <form id="demo_callback">

   <label for="get_metricUnit">Metric:</label>
   <select id="get_metricUnit">
    <option value=" km" selected="selected">kilometers</option>
    <option value=" m">meters</option>
   </select>

  <label for="length">Length:</label>
  <input id="length" meta="{
   pSign:'s', 
   aSign:'css:#get_metricUnit', 
   mDec:'fun:get_mDec', 
   aPad: false
   }" value=" km" type="text">
  </form>
  <script type="text/javascript">
  $.autoNumeric.get_mDec = function() { /* get_mDec function attached to autoNumeric() */
    var set_mDec = $('#get_metricUnit').val();
    if (set_mDec == ' km'){
     set_mDec = 3;
    } else {
     set_mDec = 0;
    }	
   return set_mDec; /* set mDec decimal places */
  }

  var get_vMax = function(){ /* set the maximum value allowed based on the metric unit */
   var set_vMax = $('#get_metricUnit').val();
   if(set_vMax == ' km'){
    set_vMax = '99999.999';
   } else {
     set_vMax = '99999999';
   }
   return set_vMax;
  }
				
  $('#length').autoNumeric({vMax: get_vMax});/* calls autoNumeric & passes function get_vMax */

  $('#get_metricUnit').change(function(){
   var set_value = $('#length').autoNumericGet();
   if (this.value == ' km'){
    set_value = set_value / 1000;
   } else { 
    set_value = set_value * 1000;
   }	
   $('#length').autoNumericSet(set_value);
  });
  </script>

Rounding options - The table below is for testing the rounding methods that are supported. Experiment by entering various values in the upper left input field. The right column will display the 9 different rounding methods. Decimal places can range from 0 to 6.

Note: If the decimal length exceeds the mDec value the result will be rounded and the remaining digits will be truncated (dropped). If the original unrounded value is required you will need to store/save the value.

For further details on rounding, the DIY Calculator site is an excellent resource. Additional information can be found on Wikipedia.

Entered value to be rounded   Rounded results



 
 
 
 
 
 
 

 

Pasting support: the value being pasted should be of the same format assigned to the target field and fall within the min\max range. Please note: if the value being pasted is not formatted it will be formatted on the keydown or blur event. Also if the value being pasted is greater or less than the min\max range the field will be cleared.

Closing comments: We hope that you find this plugin easy and useful and that it shortens your development time and saves you money. Your comments, suggestions, support and donations are appreciated.

Known issues (Help here is appreciated):

Future improvements:

Limited testing conducted on the following browsers:

History

Version 1.7.4-B

Version 1.7.4

Version 1.7.2 & 1.7.3

Version 1.7.1 click here to view

Version 1.7.0

Version 1.6.2 click here to view

Version 1.6.1

Version 1.6.0

Version 1.5.4

Version 1.5.3

Version 1.5.1

Version 1.5.0

Version 1.4.5 (Last version using the alt code) click here to view

Version 1.4.3

Versions 1.3.3 to 1.4.2: (requested custom versions)

Version 1.3.2:

Version 1.3.1:

Version 1.3.0:

Version 1.2.0 - 1.2.2: (please do not use and upgrade to 1.3.0 or greater)

Version 1.1.0 - abandoned

Original version 1.0.0 - 1.0.2

Please contact me if you have questions, comments and or suggestions at:
bob{@}decorplanit.com (remove brackets)